package cn.agrael.struts.plugin.ejb3;

import javax.annotation.Resource;
import javax.ejb.EJB;

import cn.agrael.struts.plugin.ejb3.annotation.EJBComponent;
import cn.agrael.struts.plugin.ejb3.annotation.ResourceComponent;

/**
 * 应用服务器的抽象，不同的应用服务器需要做不同的实现以解析注解及专有特性。
 * 
 * @author <a href="mailto:agraellee@gmail.com">Agrael·Lee</a>
 * 
 */
public interface ApplicationServer {

	/**
	 * 根据 fieldInjectAnnotationWrapper 的信息查找并返回对应的对象 ,
	 * {@link FieldInjectAnnotationWrapper#getInjectAnnotation()} 返回值的类型必须为
	 * {@link EJB} 。
	 * <p>
	 * 实现中应将查找正确对象的 jndi路径 调用
	 * {@link FieldInjectAnnotationWrapper#setJndiPath(String)} 放入
	 * fieldInjectAnnotationWrapper 中缓存，以便在下次解析的时候直接从缓存中获取并查找提高效率。
	 * 
	 * @param clazz 注解属于 字段 的对象的 Class 对象。
	 * @param fieldInjectAnnotationWrapper 字段注入注解包装器。
	 * @return fieldInjectAnnotationWrapper 注解包装器 所对应的对象。
	 * @throws Exception 发生任何异常时。
	 */
	Object fieldEJBAnnotationLookup(Class<?> clazz, FieldInjectAnnotationWrapper fieldInjectAnnotationWrapper) throws Exception;

	/**
	 * 根据 methodInjectAnnotationWrapper 的信息查找并返回对应的对象 ,
	 * {@link FieldInjectAnnotationWrapper#getInjectAnnotation()} 返回值的类型必须为
	 * {@link EJB} 。
	 * <p>
	 * 实现中应将查找正确对象的 jndi路径 调用
	 * {@link MethodInjectAnnotationWrapper#setJndiPath(String)} 放入
	 * methodInjectAnnotationWrapper 中缓存，以便在下次解析的时候直接从缓存中获取并查找提高效率。
	 * 
	 * @param clazz 注解属于 方法 的对象的 Class 对象。
	 * @param methodInjectAnnotationWrapper 方法注入注解包装器。
	 * @return methodInjectAnnotationWrapper 注解包装器 所对应的对象。
	 * @throws Exception 发生任何异常时。
	 */
	Object methodEJBAnnotationLookup(Class<?> clazz, MethodInjectAnnotationWrapper methodInjectAnnotationWrapper) throws Exception;

	/**
	 * 根据 fieldInjectAnnotationWrapper 的信息查找并返回对应的对象 ,
	 * {@link FieldInjectAnnotationWrapper#getInjectAnnotation()} 返回值的类型必须为
	 * {@link EJBComponent} 所标注的注解 。
	 * <p>
	 * 实现中不应该调用{@link FieldInjectAnnotationWrapper#setJndiPath(String)}，应该保证
	 * {@link FieldInjectAnnotationWrapper#getJndiPath()}返回 null 。
	 * 
	 * @param clazz 注解属于 字段 的对象的 Class 对象。
	 * @param fieldInjectAnnotationWrapper 字段注入注解包装器。
	 * @return fieldInjectAnnotationWrapper 注解包装器 所对应的对象。
	 * @throws Exception 发生任何异常时。
	 * @since 0.0.6
	 */
	Object fieldEJBComponentAnnotationLookup(Class<?> clazz, FieldInjectAnnotationWrapper fieldInjectAnnotationWrapper) throws Exception;

	/**
	 * 根据 methodInjectAnnotationWrapper 的信息查找并返回对应的对象 ,
	 * {@link FieldInjectAnnotationWrapper#getInjectAnnotation()} 返回值的类型必须为
	 * {@link EJBComponent} 所标注的注解 。
	 * <p>
	 * 实现中不应该调用{@link MethodInjectAnnotationWrapper#setJndiPath(String)}，应该保证
	 * {@link MethodInjectAnnotationWrapper#getJndiPath()}返回 null 。
	 * 
	 * @param clazz 注解属于 方法 的对象的 Class 对象。
	 * @param methodInjectAnnotationWrapper 方法注入注解包装器。
	 * @return methodInjectAnnotationWrapper 注解包装器 所对应的对象。
	 * @throws Exception 发生任何异常时。
	 * @since 0.0.6
	 */
	Object methodEJBComponentAnnotationLookup(Class<?> clazz, MethodInjectAnnotationWrapper methodInjectAnnotationWrapper) throws Exception;

	/**
	 * 根据 fieldInjectAnnotationWrapper 的信息查找并返回对应的对象 ,
	 * {@link FieldInjectAnnotationWrapper#getInjectAnnotation()} 返回值的类型必须为
	 * {@link Resource} 。
	 * <p>
	 * 实现中应将查找正确对象的 jndi路径 调用
	 * {@link FieldInjectAnnotationWrapper#setJndiPath(String)} 放入
	 * fieldInjectAnnotationWrapper 中缓存，以便在下次解析的时候直接从缓存中获取并查找提高效率。
	 * 
	 * @param clazz 注解属于 字段 的对象的 Class 对象。
	 * @param fieldInjectAnnotationWrapper 字段注入注解包装器。
	 * @return fieldInjectAnnotationWrapper 注解包装器 所对应的对象。
	 * @throws Exception 发生任何异常时。
	 */
	Object fieldResourceAnnotationLookup(Class<?> clazz, FieldInjectAnnotationWrapper fieldInjectAnnotationWrapper) throws Exception;

	/**
	 * 根据 methodInjectAnnotationWrapper 的信息查找并返回对应的对象 ,
	 * {@link FieldInjectAnnotationWrapper#getInjectAnnotation()} 返回值的类型必须为
	 * {@link Resource} 。
	 * <p>
	 * 实现中应将查找正确对象的 jndi路径 调用
	 * {@link MethodInjectAnnotationWrapper#setJndiPath(String)} 放入
	 * methodInjectAnnotationWrapper 中缓存，以便在下次解析的时候直接从缓存中获取并查找提高效率。
	 * 
	 * @param clazz 注解属于 方法 的对象的 Class 对象。
	 * @param methodInjectAnnotationWrapper 方法注入注解包装器。
	 * @return methodInjectAnnotationWrapper 注解包装器 所对应的对象。
	 * @throws Exception 发生任何异常时。
	 */
	Object methodResourceAnnotationLookup(Class<?> clazz, MethodInjectAnnotationWrapper methodInjectAnnotationWrapper) throws Exception;

	/**
	 * 根据 fieldInjectAnnotationWrapper 的信息查找并返回对应的对象 ,
	 * {@link FieldInjectAnnotationWrapper#getInjectAnnotation()} 返回值的类型必须为
	 * {@link ResourceComponent} 所标注的注解 。
	 * <p>
	 * 实现中不应该调用{@link FieldInjectAnnotationWrapper#setJndiPath(String)}，应该保证
	 * {@link FieldInjectAnnotationWrapper#getJndiPath()}返回 null 。
	 * 
	 * @param clazz 注解属于 字段 的对象的 Class 对象。
	 * @param fieldInjectAnnotationWrapper 字段注入注解包装器。
	 * @return fieldInjectAnnotationWrapper 注解包装器 所对应的对象。
	 * @throws Exception 发生任何异常时。
	 * @since 0.0.6
	 */
	Object fieldResourceComponentAnnotationLookup(Class<?> clazz, FieldInjectAnnotationWrapper fieldInjectAnnotationWrapper)
			throws Exception;

	/**
	 * 根据 methodInjectAnnotationWrapper 的信息查找并返回对应的对象 ,
	 * {@link FieldInjectAnnotationWrapper#getInjectAnnotation()} 返回值的类型必须为
	 * {@link ResourceComponent} 所标注的注解 。
	 * <p>
	 * 实现中不应该调用{@link MethodInjectAnnotationWrapper#setJndiPath(String)}，应该保证
	 * {@link MethodInjectAnnotationWrapper#getJndiPath()}返回 null 。
	 * 
	 * @param clazz 注解属于 方法 的对象的 Class 对象。
	 * @param methodInjectAnnotationWrapper 方法注入注解包装器。
	 * @return methodInjectAnnotationWrapper 注解包装器 所对应的对象。
	 * @throws Exception 发生任何异常时。
	 * @since 0.0.6
	 */
	Object methodResourceComponentAnnotationLookup(Class<?> clazz, MethodInjectAnnotationWrapper methodInjectAnnotationWrapper)
			throws Exception;
}
